indexer/rpc_client/client.go-98-105 (1)

98-105: ⚠️ Potential issue | 🟠 Major

Bound response-body size to avoid untrusted-memory blowups.

Reading arbitrary RPC response bodies with unbounded io.ReadAll can spike memory and cascade failures under bad upstream behavior.

Suggested hardening

+const maxRPCBodyBytes = 4 << 20 // 4 MiB
-body, err := io.ReadAll(resp.Body)
+body, err := io.ReadAll(io.LimitReader(resp.Body, maxRPCBodyBytes+1))
 if err != nil {
 	return fmt.Errorf("failed to read response body: %w", err)
 }
+if len(body) > maxRPCBodyBytes {
+	return fmt.Errorf("response body too large: exceeded %d bytes", maxRPCBodyBytes)
+}
 
 if resp.StatusCode != http.StatusOK {
-	return fmt.Errorf("http error %s: %s", resp.Status, string(body))
+	preview := string(body)
+	if len(preview) > 1024 {
+		preview = preview[:1024] + "..."
+	}
+	return fmt.Errorf("http error %s: %s", resp.Status, preview)
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@indexer/rpc_client/client.go` around lines 98 - 105, Replace the unbounded
io.ReadAll(resp.Body) with a size-limited read to prevent OOM: define a
package-level constant like maxResponseBodySize (e.g. 1<<20 for 1MiB), read via
io.ReadAll(io.LimitReader(resp.Body, maxResponseBodySize)), and if the returned
body length equals maxResponseBodySize treat it as an error (return a clear
"response body too large" error) instead of proceeding; update the code around
the existing resp, body, io.ReadAll and http.StatusOK checks to use the limited
reader and fail fast on oversized responses.

indexer/db_init/hypertable.go-48-53 (1)

48-53: ⚠️ Potential issue | 🟠 Major

Don’t continue after hypertable/compression setup failures.

Line 48, Line 83, and Line 112 now only log on DB DDL failures, so initialization can proceed in a broken/partial state. Please propagate errors (or aggregate and return) so startup can fail deterministically.

Suggested direction

-func (init *DBInitializer) ConvertToHypertables(tableNames []string) {
+func (init *DBInitializer) ConvertToHypertables(tableNames []string) error {
 	for _, tableName := range tableNames {
 		...
 		if err != nil {
-			l.Error()...Msgf("failed ...")
+			return fmt.Errorf("convert %s to hypertable: %w", tableName, err)
 		}
 	}
+	return nil
}

Apply the same pattern to AlterCompressionSegments and AddCompressionPolicy.

Also applies to: 83-88, 112-117

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@indexer/db_init/hypertable.go` around lines 48 - 53, The code currently only
logs failures when converting a table to a hypertable and when setting up
compression, which allows init to continue in a broken state; update the
hypertable conversion block (the log call that produces "failed to convert table
%s to hypertable: %v") and the calls to AlterCompressionSegments and
AddCompressionPolicy so that on any error you propagate or aggregate and return
the error (e.g., wrap the original error and return it from the surrounding
function) instead of only logging; ensure the calling initializer receives the
error so startup can fail deterministically.

indexer/indexer.go-30-31 (1)

30-31: ⚠️ Potential issue | 🟠 Major

Avoid Fatal() here; it bypasses deferred OTel shutdown.

Fatal() exits immediately via os.Exit(1), skipping the deferred provider shutdown at line 30. This causes pending batched telemetry/logs to be lost on command errors. Explicitly shut down the provider before exiting.

Suggested fix:

1. Store the provider's Shutdown method instead of using defer
2. On command error, log the error, explicitly call shutdown with a timeout, then os.Exit(1)
3. Add "time" to imports

Suggested patch

 import (
 	"context"
 	"os"
 	"os/signal"
 	"syscall"
+	"time"
@@
 func main() {
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer cancel()
+	var shutdownProvider func(context.Context) error
@@
 	if os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT") != "" {
 		if exp, err := otlploghttp.New(ctx); err == nil {
 			provider := sdklog.NewLoggerProvider(
 				sdklog.WithProcessor(sdklog.NewBatchProcessor(exp)),
 			)
 			global.SetLoggerProvider(provider)
-			defer provider.Shutdown(ctx) //nolint:errcheck
+			shutdownProvider = provider.Shutdown
 		}
 	}
@@
 	if err := cmd.RootCmd.ExecuteContext(ctx); err != nil {
-		logger.Get().Fatal().Err(err).Msg("failed to execute command")
+		logger.Get().Error().Err(err).Msg("failed to execute command")
+		if shutdownProvider != nil {
+			shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 5*time.Second)
+			if shutdownErr := shutdownProvider(shutdownCtx); shutdownErr != nil {
+				logger.Get().Error().Err(shutdownErr).Msg("failed to shutdown OTel logger provider")
+			}
+			shutdownCancel()
+		}
+		os.Exit(1)
 	}
 }

Also applies to: 40-42

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@indexer/indexer.go` around lines 30 - 31, The code currently defers
provider.Shutdown(ctx) (provider.Shutdown) but later calls log.Fatal/cli.Fatal
which calls os.Exit and skips deferred shutdown; change to capture the shutdown
function (e.g., shutdown := provider.Shutdown), remove the defer, and on command
error paths (the places using Fatal in this file—refer to the error handling
after provider init and the similar block at lines referenced around 40-42) call
shutdown with a cancellable context that has a timeout (use time.WithTimeout),
wait for it to complete, log the original error, then call os.Exit(1); also add
"time" to the imports.

indexer/main_operator/operator.go-103-107 (1)

103-107: ⚠️ Potential issue | 🟠 Major

Historic shutdown path currently only logs and does not stop processing.

When cancellation arrives, the goroutine logs it, but HistoricProcess keeps running without a cancellation channel/context path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@indexer/main_operator/operator.go` around lines 103 - 107, Historic
processing isn't cancelled because HistoricProcess is called without a context;
capture the signalHandler.Context() and propagate cancellation into
HistoricProcess by changing its signature to accept a context.Context (or add a
context param) and using signalHandler.Context() (or its .Done()) inside the
goroutine call site: replace orch.HistoricProcess(...) with
orch.HistoricProcess(signalHandler.Context(), runningFlags.FromHeight,
runningFlags.ToHeight, runningFlags.CompressEvents) and implement context-aware
cancellation inside HistoricProcess (check ctx.Done() and return promptly), so
the goroutine logging the shutdown will actually stop processing.

compression/train/process.go-44-67 (1)

44-67: ⚠️ Potential issue | 🟠 Major

Collection loop can over-fetch, overwhelm DB, and hide partial failures.

The current fan-out may launch thousands of concurrent DB calls, the last chunk can request beyond amount, and failed chunk fetches are only logged (function still returns success with partial data).

✅ Proposed hardening

-	goroutines = int(math.Ceil(float64(amount) / 100))
+	const chunkSize uint64 = 100
+	goroutines = int(math.Ceil(float64(amount) / float64(chunkSize)))
 	transactions := make([]*database.Transaction, 0)
 	wg := sync.WaitGroup{}
 	wg.Add(goroutines)
 	mu := sync.Mutex{}
+	errCh := make(chan error, goroutines)
 	for i := 0; i < goroutines; i++ {
 		go func(i int) {
 			defer wg.Done()
-			offset := uint64(i) * limit
+			offset := uint64(i) * chunkSize
+			if offset >= amount {
+				return
+			}
+			batchLimit := min(chunkSize, amount-offset)
 			log.Printf("getting the transactions from %s with limit %d and offset %d", chainName, limit, offset)
 			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 			defer cancel()
-			txs, err := db.GetTransactionsByOffset(ctx, chainName, limit, offset)
+			txs, err := db.GetTransactionsByOffset(ctx, chainName, batchLimit, offset)
 			if err != nil {
-				log.Printf("failed to get transactions from %s with limit %d and offset %d: %v", chainName, limit, offset, err)
+				errCh <- fmt.Errorf("failed to get transactions for offset %d: %w", offset, err)
 				return
 			}
@@
 		}(i)
 	}
 	wg.Wait()
+	close(errCh)
+	for err := range errCh {
+		if err != nil {
+			return nil, err
+		}
+	}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@compression/train/process.go` around lines 44 - 67, The fan-out loop
launching goroutines can spawn too many concurrent DB calls, request beyond the
total amount, and silently drop failures; fix by bounding concurrency (introduce
a semaphore/worker pool with a configurable maxWorkers and use it around each
goroutine spawn), compute each chunk size so the last request does not exceed
amount (calculate remaining = min(limit, amount - offset) and pass that to
db.GetTransactionsByOffset instead of always using limit), and collect/propagate
errors from db.GetTransactionsByOffset (e.g., send errors on a channel or
capture the first error and return it) rather than only logging so the caller
can detect partial failures; update references in this block (the goroutine
closure that calls db.GetTransactionsByOffset, the transactions slice append
protected by mu, and the wg synchronization) accordingly.

docker-compose-dev.yml-11-11 (1)

11-11: ⚠️ Potential issue | 🟠 Major

Avoid committed plaintext credentials in compose config.

Use environment-variable substitution (or .env) instead of hardcoded passwords.

Suggested fix

-      POSTGRES_PASSWORD: 12345678
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
@@
-      DB_PASSWORD: 12345678
+      DB_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
@@
-      DB_PASSWORD: 12345678
+      DB_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}

Also applies to: 38-39, 64-64

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docker-compose-dev.yml` at line 11, Replace hardcoded plaintext passwords in
the docker-compose-dev.yml (e.g., the POSTGRES_PASSWORD entries currently set to
"12345678" and the similar values noted at lines 38-39 and 64) with
environment-variable substitution such as referencing ${POSTGRES_PASSWORD} (or a
default like ${POSTGRES_PASSWORD:-}) and document the required variable in a
.env.example file; ensure you remove the literal password from the compose file
and update README to instruct developers to provide POSTGRES_PASSWORD via .env
or their environment instead.

api/handlers/address.go-24-41 (1)

24-41: ⚠️ Potential issue | 🟠 Major

Validate incompatible query mode combinations before DB call.

Right now a request can send cursor + range + paging together. That creates ambiguous behavior and inconsistent pagination semantics. Reject mixed modes and allow only one strategy per request.

Suggested fix

 	var fromTs, toTs *time.Time
@@
 	var cursor *string
 	if input.Cursor != "" {
 		cursor = &input.Cursor
 	}
+
+	modeCount := 0
+	if fromTs != nil || toTs != nil {
+		modeCount++
+	}
+	if cursor != nil {
+		modeCount++
+	}
+	if limit != nil || page != nil {
+		modeCount++
+	}
+	if modeCount > 1 {
+		return nil, huma.Error400BadRequest("invalid query parameters", nil)
+	}
+
 	addressTxs, nextCursor, txCount, err := h.db.GetAddressTxs(

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api/handlers/address.go` around lines 24 - 41, Before constructing
fromTs/toTs/limit/page/cursor and calling the DB, validate that the request uses
only one pagination mode: treat cursor mode as input.Cursor != "", range mode as
input.FromTimestamp or input.ToTimestamp not zero, and paging mode as
input.Limit != 0 or input.Page != 0; if more than one mode is present, return a
400 error (or the handler's standard bad-request response) and do not proceed to
the DB. Implement this check using the existing input, fromTs/toTs, limit/page,
and cursor symbols so mixed combinations (cursor + range, cursor + paging, range
+ paging) are rejected up front.

Makefile-1-12 (1)

1-12: ⚠️ Potential issue | 🟠 Major

Top-level .PHONY declaration is malformed.

Lines 1-12 show tab-indented continuation, but tabs in Makefiles introduce recipe lines (shell commands), not target prerequisites. Only build from line 1 is marked phony; the remaining targets (install, clean, build-experimental, build-api, integration-test, test, vulnerability-scan, snyk, semgrep, code-quality) are not marked phony. Consolidate all targets onto a single line and remove the duplicate .PHONY: train-zstd declaration at line 78.

Suggested fix

-.PHONY: build 
-		install 
-		clean 
-		build-experimental 
-		install-experimental 
-		build-api 
-		integration-test 
-		test 
-		vulnerability-scan 
-		snyk 
-		semgrep 
-		code-quality
+.PHONY: build install clean build-experimental install-experimental build-api integration-test test vulnerability-scan snyk semgrep code-quality train-zstd
@@
-.PHONY: train-zstd

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Makefile` around lines 1 - 12, The top-level .PHONY declaration is malformed:
only "build" is currently marked phony because the remaining targets are on
subsequent tab-indented lines (interpreted as recipe lines). Edit the Makefile
to place a single .PHONY: line listing all targets (build install clean
build-experimental install-experimental build-api integration-test test
vulnerability-scan snyk semgrep code-quality) on one line, and remove the
duplicate ".PHONY: train-zstd" declaration found later so each phony target is
declared exactly once.

docker-compose.yml-35-36 (1)

35-36: ⚠️ Potential issue | 🟠 Major

Use health-based dependency gating for DB readiness.

At Lines [35-36] and [54-55], depends_on only orders startup. indexer/api may race before TimescaleDB is ready.

🛠️ Proposed fix

-    depends_on:
-      - timescaledb
+    depends_on:
+      timescaledb:
+        condition: service_healthy
@@
-    depends_on:
-      - timescaledb
+    depends_on:
+      timescaledb:
+        condition: service_healthy

Also applies to: 54-55

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docker-compose.yml` around lines 35 - 36, Replace simple startup ordering
with health-based gating: add a healthcheck block to the timescaledb service
(e.g., a pg_isready or psql-based TEST command plus interval/timeout/retries)
and update the depends_on entries for the indexer and api services to depend on
timescaledb with condition: service_healthy instead of the current list form;
ensure the service name references are the existing timescaledb, indexer, and
api service keys so Docker Compose waits for DB readiness before starting
indexer/api.

docker-compose.yml-27-33 (1)

27-33: ⚠️ Potential issue | 🟠 Major

Do not hardcode database credentials in service definitions.

At Lines [31] and [50], plaintext passwords are embedded in compose config. Move these to external environment variables/secrets.

🔒 Proposed fix

     environment:
       DB_HOST: timescaledb
       DB_PORT: 5432
       DB_USER: postgres
-      DB_PASSWORD: 12345678
+      DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
       DB_NAME: gnoland
@@
     environment:
       DB_HOST: timescaledb
       DB_PORT: 5432
       DB_USER: postgres
-      DB_PASSWORD: 12345678
+      DB_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD}
       DB_NAME: gnoland

Also applies to: 46-51

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docker-compose.yml` around lines 27 - 33, The docker-compose service
environment block currently hardcodes DB credentials (DB_PASSWORD, DB_USER,
DB_NAME, DB_HOST, DB_PORT); remove plaintext values and load them from external
sources instead by using an env_file or Docker secrets for DB_PASSWORD (and
other sensitive vars) and reference those variables in the service's environment
section; update any other service blocks with the same environment keys to use
the same env_file/secrets approach and ensure the compose file documents the
required external .env or secret names.

api/handlers/transactions.go-150-152 (1)

150-152: ⚠️ Potential issue | 🟠 Major

Do not map all cursor query failures to 404.

At Line [151], every DB error is returned as 404 Not Found. This hides operational failures (timeouts, connection issues) as missing data and makes client behavior misleading.

🐛 Proposed fix

  if err != nil {
-		return nil, huma.Error404NotFound("Transactions by cursor not found", err)
+		return nil, huma.Error500InternalServerError("Failed to fetch transactions by cursor", err)
  }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api/handlers/transactions.go` around lines 150 - 152, The current code maps
every DB error to huma.Error404NotFound; change it to return 404 only when the
DB indicates "not found" (e.g., errors.Is(err, sql.ErrNoRows) or errors.Is(err,
gorm.ErrRecordNotFound)), otherwise return a 500/appropriate operational error
(e.g., huma.Error500InternalServerError) and log the actual error. Update the
block around the transactions-by-cursor lookup (where err is checked and
huma.Error404NotFound is used) to switch on errors.Is(err, sql.ErrNoRows) /
gorm.ErrRecordNotFound => return 404, else log the error and return a 500 error.

api/huma-types/convert.go-4-4 (1)

4-4: ⚠️ Potential issue | 🟠 Major

Input validation rejects valid 43-character unpadded base64 hashes.

The minLength/maxLength constraints at lines 4 and 8 enforce exactly 44 characters, but valid 32-byte payloads encode to 43 characters without padding. Since Huma validates these constraints before handler execution, requests with unpadded hashes are rejected before reaching base64.StdEncoding.DecodeString() or base64.URLEncoding.DecodeString(), which would otherwise accept both lengths.

✅ Proposed fix

 type ConvertFromBase64toBase64UrlInput struct {
-	TxHash64 string `query:"tx_hash_64" doc:"Input to convert" required:"true" minLength:"44" maxLength:"44"`
+	TxHash64 string `query:"tx_hash_64" doc:"Input to convert" required:"true" minLength:"43" maxLength:"44"`
 }
@@
 type ConvertFromBase64UrlToBase64Input struct {
-	TxHash64Url string `query:"tx_hash_64_url" doc:"Input to convert" required:"true" minLength:"44" maxLength:"44"`
+	TxHash64Url string `query:"tx_hash_64_url" doc:"Input to convert" required:"true" minLength:"43" maxLength:"44"`
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api/huma-types/convert.go` at line 4, The struct tag for TxHash64 is too
strict (requires 44 chars) and rejects valid 43-char unpadded base64; update the
Huma validation for the TxHash64 field to allow both 43 and 44 characters (e.g.,
minLength:"43" maxLength:"44" or remove length constraints and validate
manually) so the request reaches the handler, and ensure the handler decoding
(base64.StdEncoding.DecodeString / base64.URLEncoding.DecodeString) is used to
accept both padded and unpadded inputs.

pkgs/database/queries_address.go-186-190 (1)

186-190: ⚠️ Potential issue | 🟠 Major

Avoid lossy cursor timestamps and silent error cursors.

makeCursorParam rounds timestamps to seconds and returns "error decoding tx hash" as a cursor string on failure. This can break keyset pagination correctness and hide failures.

Suggested fix

-func makeCursorParam(
+func makeCursorParam(
 	timestamp time.Time,
 	txHash string,
-) string {
+) (string, error) {
 	txHashBytes, err := base64.StdEncoding.DecodeString(txHash)
 	if err != nil {
-		// TODO: log error
-		return "error decoding tx hash"
+		return "", fmt.Errorf("error decoding tx hash: %w", err)
 	}
-	timestamp = timestamp.Round(time.Second)
 	base64Url := base64.URLEncoding.Strict().EncodeToString(txHashBytes)
-	return timestamp.Format(time.RFC3339) + "|" + base64Url
+	return timestamp.UTC().Format(time.RFC3339Nano) + "|" + base64Url, nil
 }

-		nextCursor := makeCursorParam(lastAddressTx.Timestamp, lastAddressTx.Hash)
-		return &page, nextCursor, nil
+		nextCursor, err := makeCursorParam(lastAddressTx.Timestamp, lastAddressTx.Hash)
+		if err != nil {
+			return nil, "", err
+		}
+		return &page, nextCursor, nil

Also applies to: 252-259

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkgs/database/queries_address.go` around lines 186 - 190, The code builds a
next-cursor using makeCursorParam(lastAddressTx.Timestamp, lastAddressTx.Hash)
but makeCursorParam currently loses sub-second precision (rounds to seconds) and
returns a literal error string ("error decoding tx hash") on failure, which
corrupts keyset pagination and hides decode errors; change makeCursorParam to
preserve full timestamp precision (e.g., RFC3339Nano or unix nanoseconds) and to
return (string, error) instead of embedding error text, then update callers in
queries_address.go (where page, lastAddressTx, Timestamp, Hash are used) to
handle the error: call the new makeCursorParam, check the error, and return the
error upstream instead of returning a malformed cursor; ensure similar fixes are
applied to the other occurrence (lines ~252-259).

pkgs/database/queries_tx.go-291-296 (1)

291-296: ⚠️ Potential issue | 🟠 Major

Guard optional protobuf field dereference.

Line 295 dereferences event.PkgPath without nil check. Since event.PkgPath is an optional protobuf field of type *string, it can be nil and will panic at runtime if dereferenced without a guard.

Suggested fix

+		pkgPath := ""
+		if event.PkgPath != nil {
+			pkgPath = *event.PkgPath
+		}
 		events = append(events, Event{
 			AtType:     event.AtType,
 			Type:       event.Type,
 			Attributes: attributes,
-			PkgPath:    *event.PkgPath,
+			PkgPath:    pkgPath,
 		})

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkgs/database/queries_tx.go` around lines 291 - 296, The code appends an
Event using event.PkgPath but dereferences the optional protobuf field without a
nil check; update the append to guard event.PkgPath (e.g., compute pkgPath := ""
and if event.PkgPath != nil set pkgPath = *event.PkgPath) and use that variable
for the Event.PkgPath field so you never dereference a nil pointer (refer to the
Event struct, the events slice append, and the event.PkgPath symbol to locate
the change).

pkgs/database/queries_tx.go-14-17 (1)

14-17: ⚠️ Potential issue | 🟠 Major

Handle zstd decoder initialization errors.

Ignoring the error from zstd.NewReader on line 16 can leave the global decoder in an invalid state. This causes a silent failure during package initialization that will later panic or fail when decompressEvents (line 254) calls zstdReader.DecodeAll().

Move the initialization to an init() function and handle the error:

Suggested fix

+import "fmt"
@@
-var zstdReader, _ = zstd.NewReader(nil, zstdDict)
+var zstdReader *zstd.Decoder
+
+func init() {
+	var err error
+	zstdReader, err = zstd.NewReader(nil, zstdDict)
+	if err != nil {
+		panic(fmt.Sprintf("failed to initialize zstd decoder: %v", err))
+	}
+}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkgs/database/queries_tx.go` around lines 14 - 17, The package-level zstd
reader is created ignoring errors (dictBytes, zstdDict, zstdReader) which can
leave zstdReader nil and later crash decompressEvents when calling
zstdReader.DecodeAll(); move the zstd.NewReader(nil, zstdDict) call into an
init() function, check and handle its returned (reader, err), log/return/report
the error or panic early if initialization fails, and ensure zstdReader is only
set when err == nil so decompressEvents sees a valid reader; update any code
that assumes zstdReader is non-nil accordingly.

api/huma-types/address.go-11-12 (1)

11-12: ⚠️ Potential issue | 🟠 Major

Use pointer timestamps for truly optional query params.

FromTimestamp and ToTimestamp are optional query parameters but currently use non-pointer time.Time. This forces the handler to convert them to pointers using .IsZero() checks, creating a semantic ambiguity: zero-valued timestamps cannot be distinguished from "not provided." The downstream database layer correctly expects pointers and uses nil checks for optionality. Use pointer receivers from the start to align with Go idioms and eliminate the conversion overhead.

Suggested fix

-	FromTimestamp time.Time `query:"from_timestamp" doc:"From timestamp (inclusive)" format:"date-time"`
-	ToTimestamp   time.Time `query:"to_timestamp" doc:"To timestamp (inclusive)" format:"date-time"`
+	FromTimestamp *time.Time `query:"from_timestamp" doc:"From timestamp (inclusive)" format:"date-time"`
+	ToTimestamp   *time.Time `query:"to_timestamp" doc:"To timestamp (inclusive)" format:"date-time"`

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api/huma-types/address.go` around lines 11 - 12, Change the optional query
fields FromTimestamp and ToTimestamp in the relevant struct (currently declared
as time.Time) to pointers (*time.Time) so absence can be represented as nil;
update the struct tags (keep `query:"from_timestamp" doc:"..."
format:"date-time"`) but change the field types to *time.Time, and then update
any code that reads these fields (handlers or methods that currently use
.IsZero() checks) to use nil checks instead and pass the pointers directly to
the downstream DB layer that expects *time.Time (refer to the struct name
containing FromTimestamp/ToTimestamp and any handler function that converts
them).

pkgs/database/queries_address.go-145-156 (1)

145-156: ⚠️ Potential issue | 🟠 Major

Add tx.tx_hash to ORDER BY for first cursor page to ensure deterministic ordering.

The first cursor page (line 153) orders only by timestamp, while cursor continuation (line 175) uses (timestamp, tx_hash) tuple comparison for keyset pagination. Without matching the ordering columns, ties on timestamp can cause row duplicates or skips across pages.

Suggested fix

-		ORDER BY tx.timestamp DESC
+		ORDER BY tx.timestamp DESC, tx.tx_hash DESC

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkgs/database/queries_address.go` around lines 145 - 156, The initial query
that builds the first cursor page orders only by tx.timestamp, which mismatches
the continuation keyset pagination that compares (timestamp, tx_hash); update
the SELECT/ORDER BY used when constructing the first page (the query variable
that currently orders "ORDER BY tx.timestamp DESC") to include tx.tx_hash (e.g.,
ORDER BY tx.timestamp DESC, tx.tx_hash DESC) so it deterministically orders ties
and matches the continuation logic that uses tx_hash; ensure args (accountId,
chainName, fetchLimit) and the encode(tx.tx_hash, 'base64') projection remain
unchanged.

docs/scaling.md-1-6 (1)

1-6: ⚠️ Potential issue | 🟡 Minor

Fix title typo and intro grammar for readability.

There are a few user-facing wording issues here (Scailing, self hosted, Regardless the..., Timescaledb) that make the section feel unpolished.

✍️ Proposed edit

-# Scailing the indexer
+# Scaling the indexer

-If you use the Tiger Data (TimescaleDB cloud edition) they have some internal methods of scaling the database that
-are not present for the self hosted version.
-Regardless the Timescaledb is still a Postgres database and there are some ways to scale the indexer.
+If you use Tiger Data (TimescaleDB Cloud), it includes internal database-scaling methods that
+are not present in the self-hosted version.
+Regardless, TimescaleDB is still a Postgres database, and there are several ways to scale the indexer.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/scaling.md` around lines 1 - 6, Fix the title typo and improve wording
in the heading and first paragraph: rename the heading "Scailing the indexer" to
"Scaling the indexer", correct "self hosted" to "self-hosted", capitalize and
spell "Timescaledb" as "TimescaleDB", and rephrase the sentence starting with
"Regardless the Timescaledb is still a Postgres database..." to something like
"Regardless, TimescaleDB is still a PostgreSQL database, and there are ways to
scale the indexer." Update the instance referencing "Tiger Data (TimescaleDB
cloud edition)" for consistent capitalization and punctuation so the intro reads
clearly and professionally.

docs/scaling.md-29-32 (1)

29-32: ⚠️ Potential issue | 🟡 Minor

Fix subject-verb agreement and improve address-cache explanation.

The current sentences have grammar mismatches that make the behavior harder to understand.

✍️ Proposed edit

-The thing that you would need to pay most attention is to the address cache. The indexer has in memory cache that
-ties the address to the integer value and are mapped everywhere where some sort of address is stored.
-So for this to work you might need to copy all of the addresses from one database to another. I guess you could
-also skip this part but then this would require some sophisticated way to query from all of the shards.
+One area that needs special attention is the address cache. The indexer keeps an in-memory cache that
+maps each address to an integer value used wherever an address is stored.
+For sharding to work cleanly, you may need to copy addresses between databases. You could skip this step,
+but then you would need a more sophisticated way to query across all shards.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/scaling.md` around lines 29 - 32, Fix subject-verb agreement and clarify
the address-cache behavior in scaling.md: rewrite the paragraph so verbs agree
with their subjects and state explicitly that the indexer maintains an in-memory
address cache that maps addresses to integer IDs (reference the terms "address
cache" and "indexer"), explain that those integer IDs are used wherever
addresses are stored, and then describe the migration options clearly — either
copy all address mappings from one database to another or implement a
cross-shard query mechanism — so readers understand the consequences and
requirements.

docs/scaling.md-15-17 (1)

15-17: ⚠️ Potential issue | 🟡 Minor

Tighten the read-replica paragraph wording.

Current phrasing is grammatically awkward and repetitive, which reduces clarity.

✍️ Proposed edit

-The Postgres has a feature of read replicas. This can be used to scale the indexer if there are a lot of read
-operations. The read replicas are a copy of the database that is updated asynchronously. You would need to set up
-all of the read replicas to gather the data from the master node.
+Postgres supports read replicas. This can help scale the indexer when read traffic is high.
+Read replicas are asynchronously updated copies of the primary database. You would need to configure
+all read replicas to replicate from the primary node.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/scaling.md` around lines 15 - 17, Tighten the paragraph that begins "The
Postgres has a feature of read replicas." by replacing the awkward, repetitive
wording with a single clear sentence such as: "Postgres supports read
replicas—asynchronously updated copies of the primary database—that can be used
to scale read-heavy indexers; configuring them is outside the scope of this
project." Update the paragraph in docs/scaling.md where that sentence appears so
it reads smoothly and concisely.

docs/benchmarks.md-24-29 (1)

24-29: ⚠️ Potential issue | 🟡 Minor

Fix grammar error.

"with this settings" should be "with these settings" for correct subject-verb agreement.

📝 Proposed fix

-If you are using your own RPC node, only dedicated for the indexer by default settings it should be able to handle
-up to 900 requests concurrently. If you run the node with this settings you could in theory push the indexer to use
+If you are using your own RPC node, only dedicated for the indexer by default settings it should be able to handle
+up to 900 requests concurrently. If you run the node with these settings you could in theory push the indexer to use
 block chunk to size of 450 and transaction chunk to size of 900. However only do this if you are the only one using

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/benchmarks.md` around lines 24 - 29, In the benchmarks document update
the sentence that currently reads "If you run the node with this settings you
could in theory push..." to use correct agreement by replacing "with this
settings" with "with these settings"; locate the phrase "with this settings" in
the paragraph mentioning RPC node concurrency and change it to "with these
settings" (ensure the surrounding sentence remains grammatical).

docs/benchmarks.md-20-22 (1)

20-22: ⚠️ Potential issue | 🟡 Minor

Fix grammar error.

The phrase "the not causing" is grammatically incorrect and should be revised for clarity.

📝 Proposed fix

-For normal processing of the data, the recommended block chunk should be anywhere between 50-150. The transaction
-chunk should be anywhere between 50-300. This is a good balance between the performance and the not causing the RPC
-node to be overloaded.
+For normal processing of the data, the recommended block chunk should be anywhere between 50-150. The transaction
+chunk should be anywhere between 50-300. This is a good balance between performance and not causing the RPC
+node to be overloaded.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/benchmarks.md` around lines 20 - 22, Fix the grammar in the sentence
that reads "This is a good balance between the performance and the not causing
the RPC node to be overloaded." by rephrasing it to be clear and
grammatical—e.g., change it to "This is a good balance between performance and
avoiding overloading the RPC node." Update the sentence in the benchmarks text
where the block/transaction chunk recommendations are described.

integration/synthetic/query_operator.go-7-7 (1)

7-7: ⚠️ Potential issue | 🟡 Minor

Fix RNG seeding for deterministic synthetic data generation.

Line 152 uses unseeded global rand.Float32(), but the file claims to generate "consistent testing" data. The rest of the codebase properly seeds RNG instances (e.g., pkgs/generator/crypto.go, pkgs/generator/general.go use rand.New(rand.NewSource(seed))). Replace the global RNG call with a seeded instance stored in SyntheticQueryOperator to ensure reproducible synthetic data, aligning with the pattern used elsewhere in the generator package.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@integration/synthetic/query_operator.go` at line 7, The code uses the global
unseeded RNG via rand.Float32() (around the use in SyntheticQueryOperator) which
breaks reproducibility; modify the SyntheticQueryOperator struct to hold a
seeded *rand.Rand (constructed with rand.New(rand.NewSource(seed))) and replace
the global rand.Float32() call with op.rng.Float32() (or similar) so synthetic
data is deterministic and consistent with other generators like
pkgs/generator/crypto.go and pkgs/generator/general.go.

README.md-169-170 (1)

169-170: ⚠️ Potential issue | 🟡 Minor

Fix DB terminology typos for consistency.

Use “an easier experience” and “PostgreSQL” (not “PostgresSQL”).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 169 - 170, Update the two README bullet points to fix
terminology: change "can provide a easier experience" to "can provide an easier
experience" and replace "PostgresSQL" with the correct "PostgreSQL" (the lines
containing the phrases "an easier experience" and "PostgresSQL" in the two
bullets about SQL database and TimescaleDB).

README.md-7-19 (1)

7-19: ⚠️ Potential issue | 🟡 Minor

Documentation wording in this section needs a grammar pass.

There are several agreement/word-choice issues in this block that make the intro harder to read. Please proofread this section before merge.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 7 - 19, The README intro paragraph for "Spectra
Gnoland Indexer (SGI)" contains multiple grammar and word-choice issues; perform
a copy edit of that block (the paragraph starting with "The Spectra Gnoland
Indexer(SGI) is a tool...") to fix punctuation, spelling, subject-verb
agreement, run-on sentences, and awkward phrasing, e.g., add space in "Indexer
(SGI)", reword sentences about node endpoints/P2P and node roles for clarity,
break long sentences into shorter ones, and ensure consistent terms like
"TimescaleDB" and "RPC nodes"; keep the original meaning but produce clear,
grammatically correct, and concise prose.

docs/requirements.md-3-4 (1)

3-4: ⚠️ Potential issue | 🟡 Minor

Please fix remaining wording/typo errors in requirements.

This patch includes several clear mistakes (e.g., “could can”, “arround”, “these amount”, “PostgresSQL”) that should be corrected to keep requirements precise.

Also applies to: 23-29, 53-54, 68-69

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/requirements.md` around lines 3 - 4, Fix the typos and wording issues in
requirements.md: change "could can" to "can", "arround" to "around", "these
amount" to "this amount" (or "these amounts" if plural), and correct
"PostgresSQL" to "PostgreSQL" (or "Postgres" consistently); also review and
correct the similar mistakes on the other affected ranges (lines referenced in
the review: 23-29, 53-54, 68-69) for grammar/typos and ensure consistent
capitalization and terminology (e.g., "Tiger Data (TimescaleDB cloud edition)"
if applicable); run a quick spellcheck/proofread over the whole file to catch
remaining minor errors.

docs/api.md-17-39 (1)

17-39: ⚠️ Potential issue | 🟡 Minor

Update the route-count statement to match the new endpoint list.

This section now documents more than 5 endpoints, so the route-count text above is stale and should be updated for consistency.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/api.md` around lines 17 - 39, The route-count summary above the API
endpoints is outdated; update the route-count statement to reflect the current
number of endpoints listed under the "Blocks", "Transactions", "Addresses", and
"Utilities" sections (the list now contains more than five endpoints such as
/blocks/{height}, /blocks/latest, /transactions/{tx_hash},
/transactions/{tx_hash}/message, /address/{address}/txs, and the two /convert
routes). Edit the route-count text so it correctly states the new total (or uses
a non-specific phrasing like "multiple endpoints" if you prefer to avoid
frequent updates) and ensure it remains consistent with the endpoints shown in
the "Blocks", "Transactions", "Addresses", and "Utilities" sections.

docs/setup.md-42-42 (1)

42-42: ⚠️ Potential issue | 🟡 Minor

Fix user-facing wording/typos in updated sections.

There are a few readability issues in the modified text (e.g., “a top of the database”, “These mods”, and awkward phrasing in the live/historic guidance).

✍️ Proposed wording cleanup

-However if you are planning to add a lot of services a top of the database maybe increase it. The docker compose is
+However, if you plan to add many services on top of the database, consider increasing it. The docker compose is
@@
-These mods can be used differently together. For example you might get access to the archive RPC node. But you
+These modes can be used together in different ways. For example, you might get access to an archive RPC node, but you
@@
-Maybe you need to view at some segment of the blockchain individually. You can set up different database within the
+Maybe you need to inspect a specific segment of the blockchain individually. You can set up a different database within the
@@
-If you started the indexer with the live mode without the prior data it will try to start the indexer from the
-height 1. If the RPC node doesn't have that height it will fail. So you can use the skip-db-check flag so that the
+If you start the indexer in live mode without prior data, it will try to start from
+height 1. If the RPC node doesn't have that height, it will fail. You can use the skip-db-check flag so that live mode

Also applies to: 249-259

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/setup.md` at line 42, Fix the user-facing wording and typos in
docs/setup.md: replace "However if you are planning to add a lot of services a
top of the database maybe increase it." with clearer phrasing such as "However,
if you plan to add many services on top of the database, consider increasing its
resources." Replace informal fragments like "These mods" with "These
modifications" and rework the live/historic guidance in the other updated block
(lines referenced 249-259) to use concise, parallel phrasing (e.g., "Use the
live configuration for real-time data and the historic configuration for
archived data") and add missing commas and articles for readability.

docs/compression.md-35-36 (1)

35-36: ⚠️ Potential issue | 🟡 Minor

Minor grammar fix: use hyphen for compound adjective.

"production ready" should be hyphenated when used as a compound adjective before a noun.

📝 Proposed fix

-The current dictionary is not production ready. It was trained from the real data but the sample was small.
+The current dictionary is not production-ready. It was trained from the real data but the sample was small.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/compression.md` around lines 35 - 36, The phrase "production ready" in
docs/compression.md should be hyphenated as "production-ready" when used as a
compound adjective before "dictionary"; update the sentence in the paragraph
that currently reads "The current dictionary is not production ready." to "The
current dictionary is not production-ready." so the compound adjective is
grammatically correct.

pkgs/database/query_block.go-124-152 (1)

124-152: ⚠️ Potential issue | 🟡 Minor

Missing rows.Err() check and ORDER BY clause.

Two issues in GetFromToBlocks:

1. Unlike GetLastXBlocks, this method doesn't check rows.Err() after iterating, which could miss iteration errors.
2. The query lacks an ORDER BY clause, resulting in undefined row order (PostgreSQL doesn't guarantee order without it).

🔧 Proposed fix

 	WHERE height >= $1 AND height <= $2
 	AND chain_name = $3
+	ORDER BY height ASC
 	`
 	rows, err := t.pool.Query(ctx, query, fromHeight, toHeight, chainName)

 		blocks = append(blocks, block)
 	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
 	return blocks, nil
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkgs/database/query_block.go` around lines 124 - 152, In GetFromToBlocks, add
an ORDER BY clause to the SQL (e.g., "ORDER BY height ASC") so results have
deterministic ordering, and after iterating the rows in the for rows.Next() loop
call and return any iteration error by checking rows.Err() before returning
blocks; update the query string in GetFromToBlocks and insert a rows.Err() check
(and handle/return that error) to match the pattern used in GetLastXBlocks.

indexer/cmd/live.go-4-4 (1)

4-4: ⚠️ Potential issue | 🟡 Minor

Remove leftover debug print from CLI path.

Line 79 writes unstructured stdout output and duplicates logger intent.

Suggested fix

-import (
-	"fmt"
+import (
@@
-		fmt.Println(compressEvents)
 		mainOperator.InitMainOperator(configPath, ".", rateLimitFlags, runningFlags)

Also applies to: 79-79

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@indexer/cmd/live.go` at line 4, Remove the leftover unstructured stdout debug
print (the fmt.Println/Printf call that writes to stdout around line 79) from
indexer/cmd/live.go; delete the fmt import if it becomes unused and, if logging
is required, replace that print with the structured logger already used in this
file (use the existing logger call rather than writing to stdout).

api/handlers/address_test.go-38-39 (1)

38-39: ⚠️ Potential issue | 🟡 Minor

Use require.Len before indexing AddressTxs.

Line 39 can panic if the length assertion fails because assert is non-fatal. Use require.Len(...) before response.Body.AddressTxs[0].

Suggested fix

-	assert.Equal(t, 3, len(response.Body.AddressTxs))
+	require.Len(t, response.Body.AddressTxs, 3)
 	assert.Equal(t, "tx_hash_1", response.Body.AddressTxs[0].Hash)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api/handlers/address_test.go` around lines 38 - 39, The test currently uses
assert.Equal to check the length then indexes response.Body.AddressTxs which can
panic if the assertion fails; replace the non-fatal assert length check with a
fatal check (use require.Len(t, response.Body.AddressTxs, 3)) before accessing
response.Body.AddressTxs[0], keeping the subsequent assertion (assert.Equal(t,
"tx_hash_1", response.Body.AddressTxs[0].Hash)) unchanged so the index is safe;
update the test in address_test.go to import/use require and swap the length
assertion accordingly.

docs/data-model.md-52-53 (1)

52-53: ⚠️ Potential issue | 🟡 Minor

Fix wording typo in processing description.

At Line [52], “data is gathered and processes” should be “data is gathered and processed”.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/data-model.md` around lines 52 - 53, The sentence contains a wording
typo: replace "data is gathered and processes" with "data is gathered and
processed" in the paragraph that starts with "data is gathered and processes and
all of the transaction general data and messages contained in the transaction";
ensure the corrected phrase reads "data is gathered and processed" so the
description is grammatically correct.

docs/data-model.md-90-91 (1)

90-91: ⚠️ Potential issue | 🟡 Minor

Address table uniqueness constraints look inconsistent.

At Lines [90-91] and [95-96], marking chain_name as UNIQUE would allow only one row per chain in each address table. This likely should be a composite uniqueness on (address, chain_name) instead.

Also applies to: 95-96

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/data-model.md` around lines 90 - 91, The address table currently marks
chain_name as UNIQUE (alongside address), which incorrectly enforces one row per
chain; change the constraint so that the uniqueness is a composite key on
(address, chain_name) instead of a single-column UNIQUE on chain_name — update
the table definitions referencing the address table and the columns address and
chain_name to use a composite UNIQUE(address, chain_name) (apply the same fix to
the second occurrence noted).

compression/train/init.go-45-50 (1)

45-50: ⚠️ Potential issue | 🟡 Minor

Tighten config path validation and fix message mismatch.

At Line [49], the message says only .yml is valid, but .yaml is also accepted. Also, empty string should return a required-path error.

✅ Proposed fix

-	if configPath == nil {
+	if configPath == nil || strings.TrimSpace(*configPath) == "" {
 		return config, fmt.Errorf("config path is required")
 	}
 	if !strings.HasSuffix(*configPath, ".yml") && !strings.HasSuffix(*configPath, ".yaml") {
-		return config, fmt.Errorf("config path must end with .yml")
+		return config, fmt.Errorf("config path must end with .yml or .yaml")
 	}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@compression/train/init.go` around lines 45 - 50, The config path validation
around the configPath variable should be tightened: ensure you treat both nil
and empty (e.g., strings.TrimSpace(*configPath) == "") as a missing required
path and return an error from the same check, and update the suffix validation
to require either ".yml" or ".yaml" with an error message that matches (e.g.,
"config path must end with .yml or .yaml") — locate the validation logic that
returns errors around configPath in compression/train/init.go and adjust the
conditions and messages accordingly.

compression/cmd/main.go-31-34 (1)

31-34: ⚠️ Potential issue | 🟡 Minor

Fail fast when --config is missing.

At Line [31], an empty config path falls through and later triggers a misleading extension error. Validate emptiness right after reading the flag.

✅ Proposed fix

 import (
 	"log"
 	"os"
+	"strings"
@@
 		configPath, err := cmd.Flags().GetString("config")
 		if err != nil {
 			log.Fatalf("failed to get config path: %v", err)
 		}
+		if strings.TrimSpace(configPath) == "" {
+			log.Fatal("config path is required")
+		}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@compression/cmd/main.go` around lines 31 - 34, After reading the config flag
into configPath using cmd.Flags().GetString("config"), validate that configPath
is not empty and fail fast if it is: immediately check if configPath == "" and
call log.Fatalf with a clear message (e.g., "missing --config flag") so the
program exits with a helpful error instead of allowing later misleading errors;
add this check right after the GetString call where configPath is defined.

Dockerfile-api (3)

19-19: Empty placeholder config may cause runtime issues.

touch config-api.yml creates an empty file. Per api/config/loader.go (lines 54-70), LoadConfig uses yaml.Unmarshal on the file contents. While Host and Port have defaults, an empty file may still cause parsing issues or missing required fields at runtime.

Consider either:

1. Not copying a config file (let users mount their own)
2. Creating a minimal valid YAML config with defaults

Option: Create minimal valid config

-RUN touch config-api.yml
+RUN echo "# Default API config - override at runtime" > config-api.yml

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Dockerfile-api` at line 19, The Dockerfile currently runs "touch
config-api.yml" which creates an empty config that can break yaml.Unmarshal in
LoadConfig (function LoadConfig in api/config/loader.go); replace this
placeholder with either (A) remove the touch and let operators mount their own
config, or (B) create a minimal valid YAML config file containing the required
fields and sensible defaults (Host, Port, and any required keys referenced by
LoadConfig) so yaml.Unmarshal always receives valid YAML; update the RUN step to
write that minimal YAML instead of touching an empty file and ensure the
filename matches what LoadConfig expects.

---

20-20: chmod +x is unnecessary for Go binaries.

Go's build output is executable by default. This line can be removed.

Remove unnecessary chmod

 RUN touch config-api.yml
-RUN chmod +x build/api

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Dockerfile-api` at line 20, Remove the redundant executable permission
change: delete the RUN chmod +x build/api instruction in the Dockerfile since Go
build artifacts (the build/api binary) are already executable by default; simply
remove that RUN line to simplify the Dockerfile and avoid unnecessary steps.

---

1-1: Update to Go 1.26.0, the latest stable release.

Go 1.25 is available, but Go 1.26.0 was released on February 10, 2026 and is now the current stable version. Update the base image to golang:1.26 to use the latest stable release.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@Dockerfile-api` at line 1, Update the Dockerfile base image FROM directive to
use the new Go stable release by changing the existing FROM golang:1.25
reference to FROM golang:1.26 (or golang:1.26.0) in the Dockerfile's FROM line
so the build uses Go 1.26; ensure any other Dockerfiles or CI workflows
referencing golang:1.25 are updated consistently.

indexer/cmd/setup.go (1)

290-292: Add contextual error logging for config creation failures

Line 290-Line 292 returns raw errors without command context. Logging file path here keeps error diagnostics consistent with the rest of this file.

💡 Proposed fix

 		overwrite, _ := cmd.Flags().GetBool("overwrite")
 		if err := createConfig(overwrite, configFileName); err != nil {
+			l.Error().Err(err).Str("file", configFileName).Msg("failed to create config file")
 			return err
 		}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@indexer/cmd/setup.go` around lines 290 - 292, Wrap the raw error returned
from createConfig(overwrite, configFileName) with contextual information
including the configFileName (and command/context if appropriate) instead of
returning err directly; e.g., replace the plain return err with returning a
wrapped error that includes "failed to create config" and the configFileName
using fmt.Errorf or errors.Wrap so callers/logs show the file path and command
context; locate the call to createConfig and update its error return
accordingly.

indexer/data_processor/event.go (1)

75-76: ⚠️ Potential issue | 🟡 Minor

Compression contract still conflicts with runtime behavior.

Line 75 says useCompressed=true returns compressed format, but Line 91 still requires evCount >= 2. Either update the doc contract or make behavior deterministic on useCompressed alone.

Also applies to: 91-91

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@indexer/data_processor/event.go` around lines 75 - 76, The comment vs runtime
disagree: the header says useCompressed=true should return compressed format but
the implementation still gates compression on evCount >= 2; update the code so
behavior is deterministic based only on useCompressed (or update the doc to
state the evCount requirement). Concretely, in event.go change the branch that
currently checks evCount before compressing to instead check useCompressed
(i.e., if useCompressed then produce compressed output regardless of evCount;
otherwise produce native), and adjust or remove the evCount condition and update
the header comment to match the final behavior; reference the variables
useCompressed and evCount in the affected function to locate the logic to
change.

indexer/cmd/setup.go (1)

224-242: ⚠️ Potential issue | 🟠 Major

Avoid Fatal() inside RunE; return explicit errors after printing usage.

On Line 224, Line 231, Line 234, Line 241, Line 248, Line 260, and Line 267, l.Fatal() in a RunE path can short-circuit command error propagation. Also, Line 232, Line 235, and Line 242 returning cmd.Usage() is unreliable for validation failures; return a non-nil validation error after calling usage.

💡 Proposed fix

 import (
 	"context"
+	"errors"
 	"time"
@@
 		params, err := parseCommonFlags(cmd, "gnoland")
 		if err != nil {
-			l.Fatal().Err(err).Msg("failed to parse flags")
+			l.Error().Err(err).Msg("failed to parse flags")
 			return err
 		}
@@
 		privilege, _ := cmd.Flags().GetString("privilege")
 		if privilege == "" {
-			l.Fatal().Msg("privilege is required")
-			return cmd.Usage()
+			l.Error().Msg("privilege is required")
+			_ = cmd.Usage()
+			return errors.New("privilege is required")
 		} else if privilege != "reader" && privilege != "writer" {
-			l.Fatal().Str("privilege", privilege).Msg("invalid privilege")
-			return cmd.Usage()
+			l.Error().Str("privilege", privilege).Msg("invalid privilege")
+			_ = cmd.Usage()
+			return errors.New("invalid privilege: must be reader or writer")
 		}
@@
 		userName, _ := cmd.Flags().GetString("user")
 		if userName == "" {
-			l.Fatal().Msg("user name is required")
-			return cmd.Usage()
+			l.Error().Msg("user name is required")
+			_ = cmd.Usage()
+			return errors.New("user name is required")
 		}
@@
 		params.password, err = promptPassword()
 		if err != nil {
-			l.Fatal().Err(err).Msg("failed to read password")
+			l.Error().Err(err).Msg("failed to read password")
 			return err
 		}
@@
 		err = dbInit.CreateUser(userName)
 		if err != nil {
-			l.Fatal().Err(err).Str("user", userName).Msg("failed to create user")
+			l.Error().Err(err).Str("user", userName).Msg("failed to create user")
 			return err
 		}
@@
 		err = dbInit.AppointPrivileges(userName, privilege, []string{})
 		if err != nil {
-			l.Fatal().Err(err).Str("user", userName).Str("privilege", privilege).Msg("failed to appoint privileges")
+			l.Error().Err(err).Str("user", userName).Str("privilege", privilege).Msg("failed to appoint privileges")
 			return err
 		}

#!/bin/bash
# Verify logger fatal semantics and affected call sites.
fd logger.go
sed -n '1,240p' pkgs/logger/logger.go
rg -n -C2 '\.Fatal\(' indexer/cmd/setup.go
rg -n -C2 'return cmd\.Usage\(\)' indexer/cmd/setup.go

Also applies to: 248-249, 260-268

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@indexer/cmd/setup.go` around lines 224 - 242, Replace l.Fatal() calls inside
the RunE implementation with non-fatal logging (e.g., l.Error() or l.Warn()),
call cmd.Usage() only to print usage, and then return an explicit non-nil
validation error (e.g., fmt.Errorf("missing privilege") or fmt.Errorf("invalid
privilege: %s", privilege)). Specifically, update the checks that use
cmd.Flags().GetString("privilege") and cmd.Flags().GetString("user") (and any
other similar flag checks) to log via l.Error()/l.Warn(), invoke cmd.Usage() to
show help, and return a clear error instead of returning cmd.Usage() or calling
l.Fatal(); preserve existing log fields (like .Str("privilege", privilege)) when
converting to non-fatal logs. Ensure all instances of l.Fatal() in RunE are
handled this way so command error propagation remains intact.

pkgs/database/queries_tx.go (1)

168-176: ⚠️ Potential issue | 🟠 Major

Offset pagination still omits compression fields used by ToTransaction.

At Line 168-Line 176 and Line 190, GetTransactionsByOffset does not select/scan tx_events_compressed and compression_on. In pkgs/database/types_api.go (FullTxData.ToTransaction), decoding is gated by CompressionOn, so compressed rows are not reconstructed on this path.

Suggested fix

 	SELECT
 	encode(tx.tx_hash, 'base64') AS tx_hash,
 	tx.timestamp,
 	tx.block_height,
 	tx.tx_events,
+	tx.tx_events_compressed,
+	tx.compression_on,
 	tx.gas_used,
 	tx.gas_wanted,
 	tx.fee,
 	tx.msg_types
@@
-		err := rows.Scan(&transaction.TxHash, &transaction.Timestamp, &transaction.BlockHeight, &transaction.TxEvents, &transaction.GasUsed, &transaction.GasWanted, &transaction.Fee, &transaction.MsgTypes)
+		err := rows.Scan(
+			&transaction.TxHash,
+			&transaction.Timestamp,
+			&transaction.BlockHeight,
+			&transaction.TxEvents,
+			&transaction.TxEventsCompressed,
+			&transaction.CompressionOn,
+			&transaction.GasUsed,
+			&transaction.GasWanted,
+			&transaction.Fee,
+			&transaction.MsgTypes,
+		)

Also applies to: 190-195

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkgs/database/queries_tx.go` around lines 168 - 176, GetTransactionsByOffset
is missing the compressed fields so rows with compressed event payloads never
reconstruct via FullTxData.ToTransaction; update the SELECT in
GetTransactionsByOffset to include tx_events_compressed and compression_on (same
as the cursor pagination path at lines ~190) and update the corresponding
scan/dest variables in the GetTransactionsByOffset query handling so
FullTxData.CompressionOn and FullTxData.TxEventsCompressed are populated before
calling ToTransaction.

pkgs/database/queries_address.go (1)

257-259: ⚠️ Potential issue | 🟠 Major

Cursor timestamp precision is still truncated (previously reported).

This still rounds to seconds and serializes/parses with time.RFC3339, which can break page boundaries when multiple transactions share a second.

🧭 Proposed fix

-	timestamp = timestamp.Round(time.Second)
 	base64Url := base64.URLEncoding.Strict().EncodeToString(txHashBytes)
-	return timestamp.Format(time.RFC3339) + "|" + base64Url
+	return timestamp.Format(time.RFC3339Nano) + "|" + base64Url
@@
-	timestamp, err := time.Parse(time.RFC3339, parts[0])
+	timestamp, err := time.Parse(time.RFC3339Nano, parts[0])

#!/bin/bash
# Verify cursor precision handling in pkgs/database/queries_address.go
cat -n pkgs/database/queries_address.go | sed -n '248,274p'

Expected after fix: no Round(time.Second) and RFC3339Nano used in both cursor marshal/unmarshal.

Also applies to: 269-270

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkgs/database/queries_address.go` around lines 257 - 259, Remove the
second-level rounding and switch to nanosecond precision when
serializing/parsing the cursor: stop calling timestamp =
timestamp.Round(time.Second) and instead format the timestamp with
time.RFC3339Nano (replace timestamp.Format(time.RFC3339) with
timestamp.Format(time.RFC3339Nano)), and update the corresponding cursor
parse/unmarshal logic to use time.Parse(time.RFC3339Nano, ...) so page
boundaries aren’t lost when multiple transactions share a second; apply the same
change to the other cursor serialization site around the base64Url/txHashBytes
code (the other occurrence noted at the 269-270 region).

pkgs/database/queries_tx.go (1)

3-8: Use the structured logger consistently in DB query errors.

Line 75 uses log.Println while this file already uses logger.Get() (l) for structured logging. Switching this path keeps logs consistent with the rest of the module.

Suggested refactor

 import (
 	"context"
 	"encoding/base64"
-	"log"
 	"strconv"
@@
-		log.Println("error getting transaction", err)
+		l.Error().Err(err).Str("chain_name", chainName).Str("tx_hash", txHash).Msg("error getting transaction")
 		return nil, err

Also applies to: 75-76

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkgs/database/queries_tx.go` around lines 3 - 8, Replace the plain std log
usage at the log.Println call with the module's structured logger obtained via
logger.Get() (variable l) so DB query errors are logged consistently; update the
call site that currently uses log.Println to use l.Error / l.Errorf (or l.Errorw
with fields) and include the error/context fields, remove the unused "log"
import, and apply the same replacement for the other occurrence noted (the two
occurrences around the log.Println call).

pkgs/database/queries_address.go (2)

248-256: Don’t return sentinel cursor text on decode failure; propagate the error.

Returning "error decoding tx hash" creates an invalid cursor string and hides the underlying failure path.

🛠️ Proposed fix

-func makeCursorParam(
+func makeCursorParam(
 	timestamp time.Time,
 	txHash string,
-) string {
+) (string, error) {
 	txHashBytes, err := base64.StdEncoding.DecodeString(txHash)
 	if err != nil {
-		// TODO: log error
-		return "error decoding tx hash"
+		return "", fmt.Errorf("error decoding tx hash: %w", err)
 	}
 	timestamp = timestamp.Round(time.Second)
 	base64Url := base64.URLEncoding.Strict().EncodeToString(txHashBytes)
-	return timestamp.Format(time.RFC3339) + "|" + base64Url
+	return timestamp.Format(time.RFC3339) + "|" + base64Url, nil
 }
@@
-		nextCursor := makeCursorParam(lastAddressTx.Timestamp, lastAddressTx.Hash)
-		return &page, nextCursor, nil
+		nextCursor, err := makeCursorParam(lastAddressTx.Timestamp, lastAddressTx.Hash)
+		if err != nil {
+			return nil, "", err
+		}
+		return &page, nextCursor, nil

Also applies to: 189-190

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkgs/database/queries_address.go` around lines 248 - 256, The function
makeCursorParam should not swallow the base64 decode error; change its signature
to return (string, error), return ("", err) (or wrapped fmt.Errorf with context)
when base64.StdEncoding.DecodeString(txHash) fails instead of returning the
sentinel string, and update all callers of makeCursorParam to handle the error.
Apply the same change to the other similar helper that currently returns "error
decoding tx hash" so both places propagate the decode error and include
contextual error messages.

---

25-27: Update the function doc comment to match the actual return signature.

The comment still documents two return values, but the function now returns (*[]AddressTx, string, uint64, error).

Also applies to: 37-37

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pkgs/database/queries_address.go` around lines 25 - 27, Update the function
doc comment that currently lists two return values ("- []*AddressTx" and "-
error") so it matches the actual return signature of the function (returning
(*[]AddressTx, string, uint64, error)); specifically replace the old two-item
bullets with four bullets describing: *[]AddressTx (transactions), string
(cursor/next-token), uint64 (count/total) and error to reflect the new return
types used by the function.